home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1997 September / Macworld (1997-09).dmg / Shareware World / Utilities / Text Processing / Alpha / Help / BibTeX Help < prev    next >
Text File  |  1995-07-31  |  15KB  |  385 lines
  1. #####################
  2. BibTeX mode for Alpha
  3. #####################
  4.  
  5. This document describes features of Bib mode and the BibTeX menu, which 
  6. were written to simplify the use and maintenance of BibTeX citation 
  7. database files.
  8.  
  9. Bib Mode
  10. ========
  11.  
  12. Bib mode is entered when you open a file with a '.bib' suffix, or 
  13. when select the mode explicitly from the modes menu.  In Bib mode,
  14.  
  15. • A BibTeX menu is added to the menubar.  Commands available from this 
  16.   menu are summarized in the next section below.
  17.        
  18. • Selecting 'Mark File' in the Marks menu, "{}" on the sidebar, will 
  19.   add an index mark for the cite-key of each entry in the bib file.
  20.  
  21.   Marks are added in order of appearance in the file.  To order them 
  22.   alphabetically, use the "Sort Marks…:Alphabetically" command on the 
  23.   Bibtex menu.
  24.  
  25. • Key words in Bib files are automatically colorized.
  26.  
  27. • Double-clicking on an abbreviation string with the command key held 
  28.   down ("command-double-clicking") will move the cursor to the definition 
  29.   of that abbreviation.
  30.  
  31. • Command-double-clicking on the cite-key of a "crossref" field will 
  32.   move the cursor to the referenced entry.
  33.  
  34.  
  35. BibTeX menu
  36. ===========
  37.  
  38. Here's a description of the commands available from the BibTeX menu:
  39. (key bindings are indicated where available)
  40.  
  41. BibTeX interaction
  42. ------------------
  43.  
  44. Bibtex        Switch to the BibTeX application (launching it if necessary).
  45.  
  46. Template insertion
  47. ------------------
  48.  
  49. Entries >     Insert a template for any of the various BibTeX bibliography 
  50.             entry types (as in Tex mode).
  51.     
  52.             By default, only the required fields an the entry are included in 
  53.             the template.  This can be customized as described below.
  54.             
  55.             Choosing "Custom Entry" lets you pick the fields to be included
  56.             from a list of all fields.
  57.  
  58. Fields >     Insert a template for any of the various BibTeX bibliography 
  59.             data fields.
  60.             
  61.             Choosing "Custom Field" inserts a template without a pre-written 
  62.             field name.
  63.                         
  64.             Choosing "Multiple Fields" lets you pick the a number fields to 
  65.             be included at once.
  66.  
  67. Entry Navigation, etc.
  68. ----------------------
  69.    
  70. Select Entry    Select (highlight) the current entry (in which the cursor sits), 
  71.                 allowing the entry to be easily moved, copied or deleted.
  72.                 (Ctl-Shift-B)
  73.    
  74. Next Entry        Jump to the top of the next entry.
  75.                  (Ctl-Shift-N)
  76.    
  77. Prev Entry        Jump to the top of the previous entry.
  78.                  (Ctl-Shift-P)
  79.    
  80. Format Entry    Reformat the current entry in a standard form, with data 
  81.                 fields indented and aligned, and data-field delimiters 
  82.                 made uniform.
  83.                 (Ctl-Shift-L)
  84.                 
  85.                 Afterwards, Alpha jumps forward to the next entry, so you 
  86.                 can keep hitting Ctl-Shift-L to reformat a number of entries 
  87.                 in a row.
  88.                 
  89.                 The format may be customized using the formatting flags 
  90.                 and variables in the flags menu ("√" on the sidebar).
  91.                 
  92. Copy Cite Key    Copy the cite key for the current entry to the clipboard
  93.  
  94. Sorting and Searching
  95. ---------------------
  96.  
  97. Search Entries    Search for entries that match a given regular expression.
  98.                  (Ctl-Shift-M)
  99.    
  100. Search Fields    Search for entries in which a particular field matches a 
  101.                 regular expression.
  102.                 (Ctl-Shift-F)
  103.                 
  104.                 Entries found in a search will be copied to a new window 
  105.                 (the default) or back into the original buffer, replacing 
  106.                 the previous contents of the buffer; this is controlled by 
  107.                 the "overwriteBuffer" mode flag.
  108.     
  109. Sort by… >        Sort the database by one of various criteria...
  110.  
  111.     Cite Key            Sort by the citatation key
  112.     
  113.     First Author, Year    Sort by first or last author, and secondarily by year
  114.     Last Author, Year
  115.     
  116.     Year, First Author    Sort by year, and secondarily by first or last author
  117.     Year, Last Author 
  118.  
  119.                 The "overwriteBuffer" mode flag also controls whether the 
  120.                 sorted database is written back to the original buffer or into 
  121.                 a new one.
  122.     
  123. Sort Marks… >    
  124.  
  125.     Alphabetically    Sort the index marks on the marks menu alphabetically.
  126.     
  127.     By Position        Sort the index marks by the position of the entry.
  128.     
  129. Other
  130. -----
  131.  
  132. Count Entries        Report the total number of entries, as well the number
  133.                     of entries of each type. 
  134.  
  135. Format All Entries    Reformat the current entry and all subsequent entries to
  136.                     end of the file.
  137.                     
  138.                     You can interrupt this by hitting the "Cmd-." key
  139.  
  140.  
  141. Mode Flags and Variables
  142. ========================
  143.  
  144. The behavior of the Bibtex menu may be controlled using by setting the 
  145. various flags and variables in the flags menu ("√") on the sidebar.  
  146. These are...
  147.  
  148. …For Entry Formatting
  149. ---------------------
  150.  
  151. alignEquals     Line up the "=" signs for all fields when reformatting
  152.  
  153. entryBraces        Use curly braces to delimit entries (otherwise parentheses 
  154.                 are used).
  155.  
  156. fieldBraces        Use curly braces to delimit field values (otherwise 
  157.                 quotation marks are used).
  158.  
  159. zapEmptyFields     Remove optional fields if they're empty.
  160.     
  161.                 
  162. fillColumn        The maximum width of each line in the field value.                
  163.  
  164. indentString    Define the indentation string for field names.
  165.  
  166. stdAbbrevs        Define standard abbreviations (which we avoid surrounding 
  167.                 with delimiters) that do not appear in @string entries.
  168.                 
  169.                 By default, the three-letter English month names are included.
  170.  
  171. …For Sorting and Searching
  172. --------------------------
  173.  
  174. overwriteBuffer        Allow sorts and searches to replace the original window 
  175.                     contents. (Otherwise they are written to a new window.)
  176.     
  177.         Note:    The contents of a ".bib" file, will never be overwritten by 
  178.                 a search, since entries are typically lost.
  179.                      
  180.                 A ".bib" file _can_ be overwritten by a sort, since no 
  181.                 entries are lost.
  182.  
  183. descendingYears        Sort by year in descending order (most recent to oldest)
  184.  
  185. markStrings            Include @string definitions in the marks menu.
  186.  
  187. segregateStrings    Collect all @string definitions together at the top
  188.                     of the file in sorts.  (Otherwise sort alphabetically)
  189.  
  190.                 
  191. Key Bindings
  192. ============
  193.  
  194. Most of these functions (except template insertion) are also bound to 
  195. keystrokes.  The standard bindings are
  196.  
  197.     Ctl-Shift-N     next entry
  198.     Ctl-Shift-P     previous entry
  199.  
  200.     Ctl-Shift-B     select entry   
  201.     Ctl-Shift-L     format entry
  202.  
  203.     Ctl-Shift-M     search entries
  204.     Ctl-Shift-F     search fields
  205.  
  206.             tab     next tab stop      (as in TeX mode)
  207.       Shift-tab     previous tab stop  ( "  "  "   "  )
  208.         Ctl-tab     nth tab stop       ( "  "  "   "  )
  209.         Cmd-tab     clear tab stop     ( "  "  "   "  )
  210.         
  211.         Opt-tab     insert a real tab  ( "  "  "   "  )
  212.  
  213. Although the TeX-mode keybindings aren't available in Bib mode, the 
  214. LaTeX menu is left on the menubar.  This may be useful for inserting the
  215. various text-style codes that are recognized in BibTeX fields. 
  216.  
  217.  
  218. Customizing Entry Templates
  219. ===========================
  220.  
  221. Only the required fields are included by default when a new bib entry is 
  222. created.  You can select any other set of fields by adding an 
  223. appropriate entry to the 'myFld' array, following the example for the 
  224. Article entry in the file ":SystemCode:bibtex.tcl", accessible through 
  225. the Filesets menu.
  226.  
  227. Some day I'll make it easier to customize this, but for now it's 
  228. necessary to modify bibtex.tcl.
  229.  
  230. You should _not_ change the 'rqdFld' or 'optFld' arrays, since these 
  231. will (some day) be used for syntax checking.
  232.  
  233.  
  234. Bugs, etc.
  235. ==========
  236.  
  237. Bug reports, complaints and suggestions are very welcome.  Most of the 
  238. improvements and bug fixes made since the last major release (2.0) were
  239. the result of reports and suggestions from users.
  240.  
  241. Reports can be directed to the author at
  242.  
  243.      Tom Pollard    <pollard@cucbs.chem.columbia.edu>
  244.  
  245. You can also send mail to Tom Scavo (trscavo@syr.edu> or Pete Keleher 
  246. <keleher@cs.umd.edu> and they'll forward your comments to me.
  247.  
  248.  
  249. Version History
  250. ---------------
  251.  
  252. 2.7  (7/95)   'stdAbbrevs' modeVar added for setting predefined abbrevs
  253.               month names included as predefined abbrevs
  254.               'alignEquals' formatting flag added.
  255. 2.62 (7/95)   field delimiters suppressed if field data is an abbreviation
  256.               unindexed .bib files are indexed automatically upon opening
  257. 2.61 (7/95)   fixed "SearchFields" bug.
  258. 2.6  (6/95)   'zapEmptyFields' flag forces optional fields to be removed 
  259.                   when reformatting an entry.
  260.               'markStrings' flag controls whether @string entries are included in 
  261.                   the marks menu.
  262.               'descendingYears' flag controls whether sorts are in ascending or 
  263.                   descending chronological order.
  264.               Sorts all use the year as either primary or secondary sort key now.
  265.               'copyCiteKey' command copies the citekey of the current entry to the
  266.                   clipboard.
  267.               Cmd-double-clicking implemented to resolve abbreviations and crossrefs.
  268.               Fixed bug in faster getFields proc (comma-after-last-field problems)  
  269.               Fixed minor bugs in author sorting.  
  270. 2.5  (6/95)   Fixed bug in formatEntry, whereby '#' concatenations were lost 
  271.               formatEntry completely ignores @string entries now
  272.               Entry-parsing code (getFields, getFldVal) cleaned up,
  273.                  should also be a little bit faster now.
  274.               formatAllEntries now starts working from the current entry
  275. 2.41 (6/95)   Updates for compatibility with revised LaTeX mode
  276.               Automatic conversion of international characters dropped 
  277.                   (irreconcilable problems with non-US keyboards).
  278. 2.4  (5/95)   Fixed bugs in parsing of EndNote-created bib files
  279. 2.3  (4/95)   International characters converted to TeX codes (optionally).
  280.               'findEntries' bug fixed (no longer returns multiple hits) 
  281. 2.2 (12/94)   'formatEntries' won't quote fields that contain "#".
  282.               'segregateStrings' flag forces string defs to sort to the top.
  283. 2.11(12/94)   Bug fixes in 'formatAllEntries'.
  284. 2.1 (12/94)   'countEntries' command added.
  285.               'formatAllEntries' command added; it's a bit clunky, but more robust
  286.                   than any quicker alternative I considered.
  287.               Cross-referenced entries now sort to the bottom in all sorts.
  288.               'crossref' field now included.
  289. 2.0 (9/94)    'formatEntry' and 'newEntry' line up fields better.
  290.               'nextEntry' and 'prevEntry' skip @string defs
  291.               'formatEntry' automtically goes to next entry afterwards.
  292.               'sortByCitekey' ignores case of cite keys.
  293.               'fillColumn' included as default modeVar.
  294.               'getEntry' alerts user to badly delimited entries.
  295. 1.9 (9/94)    'getFields' should now correctly parse any legal entry.
  296.               'language' field now included.
  297.               Default values for new fields (eg 'language') may be defined
  298.               'preferBraces' replaced by 'fieldBraces' and 'entryBraces'.
  299.               line-wrapping is done on reformatted entries.
  300.               '@string' entries preserved in sorts.
  301.               text before first entry and after last entry are preserved
  302.                   by sorts.
  303. 1.8 (8/94)    "getEntry" now recognizes parens as entry delimiters
  304. 1.7 (8/94)    Bug fixes and accomodations to latex.tcl v2.2
  305.               Template insertion streamlined
  306.               Choose multiple fields at a time from a list dialog
  307. 1.6 (8/94)    "preferBraces" allows braces or quotes to be default for
  308.                   new or reformatted entries,
  309.               Menu built using $entryNames and $fieldNames,
  310.               'sortByAuthors' can now sort using last author first,
  311.                   and is a bit faster,
  312.               'formatEntry' rewrites entries in canonical format,
  313.               More customization of canonical format allowed ('indentString')
  314.               Bib mode definition adapted to Alpha 5.90.
  315. 1.5 (7/94)    "sortByAuthors" is now robust,
  316.               Mode of new windows now set correctly.
  317. 1.4 (7/94)    Added sorting by authors, but still only semi-functional,
  318.               Added regexp searching by field,
  319.               "getEntry" bugs fixed.
  320. 1.2 (7/94)    Bib mode definition adapted to Alpha 5.85,
  321.               Added bib-file marking (bibMarkFile),
  322.               Entry and field creation now controlled by data arrays.
  323. 1.1 (6/94)    Custom BibTeX icon, 
  324.               Added simple search capability (matchingEntries).
  325. 1.0 (9/93)    First stable version.
  326.  
  327.  
  328. Future Directions
  329. -----------------
  330.  
  331. These are come of the ideas I'm considering for future enhancements to 
  332. the BibTeX support package (roughly in the order they're likely to be 
  333. addressed).  I welcome any comments or additional ideas people may have.
  334.  
  335. 1.    Some sort of consistency and/or syntax checking of the database; for
  336.     instance, verifying that all entries have the required fields and 
  337.     checking for duplicate entries.
  338.  
  339. 2.    Speed up entry reformatting
  340.  
  341. 3.  Allowing the user to interactively choose the standard fields used 
  342.     for a given entry type.
  343.     
  344. 4.  Allowing more complicated searches.  Logical 'AND' searches can be 
  345.     done now by doing additional searches on the results of previous ones.  
  346.     It would be nice to allow logical 'OR' searches by concatenating the 
  347.     results of successive searches to a database in the same buffer.  Ideas 
  348.     for simple, intuitive ways to control this would be welcome.
  349.  
  350. ?.  Since the code parses BibTeX entries already, it would be easy to 
  351.     export .bib files to other formats, but I'm not sure if it's a good idea 
  352.     to start burdening Alpha with that sort of thing.  Writing Perl scripts 
  353.     for file conversions is probably a better idea.  See, for instance, the 
  354.     "CC to BibTeX" Perl script (included in the :Tcl:UserCode:TextFilters 
  355.     folder), which converts citations from the on-line Current Contents 
  356.     database (the one at UC Berkeley, anyway) to BibTeX format.  
  357.  
  358.  
  359. BibTeX application
  360. ==================
  361.  
  362. If you don't already have a BibTeX application, version 2.0 of MacBibTeX
  363. can found at the following URL
  364.  
  365.    ftp://ftp.bluesky.com/ftp-area/pub/utilities/BibTeX.sea.hqx
  366.    
  367. (You can download it by selecting the above URL and running the
  368. 'sendURL' command from the' Utils' menu.)
  369.  
  370. MacBibTeX was written by
  371.  
  372.     Jim Studt        <jim@wucs1.wustl.edu>   , and
  373.     Michael Kahn    <kahn@wucs1.wustl.edu>
  374.     
  375. based on Oren Patashnik's original BibTeX 0.99c .
  376.  
  377. Acknowledgments
  378. ===============
  379.  
  380. This package was inspired by LaTeX support package (latex.tcl), written by
  381.  
  382.    Tom Scavo          <trscavo@syr.edu>  , and (originally),
  383.    Richard T. Austin  <austin@eecs.umich.edu>
  384.    
  385. ---------------------------------------------------------------------------